home *** CD-ROM | disk | FTP | other *** search
/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / dev / c / PhoneLogDevKit.lha / PhoneLog / docs / PhoneLogGenerator.doc < prev    next >
Encoding:
Text File  |  1996-03-16  |  17.2 KB  |  550 lines
  1. TABLE OF CONTENTS
  2.  
  3. PhoneLog/--announce--
  4. PhoneLog/--background--
  5. PhoneLog/--compiling--
  6. PhoneLog/--history--
  7. PhoneLog/--release--
  8. PhoneLog/--todo--
  9. PhoneLogGenerator/ClosePhoneLog
  10. PhoneLogGenerator/OpenPhoneLog
  11. PhoneLogGenerator/WritePhoneLogEndEntry
  12. PhoneLogGenerator/WritePhoneLogEntry
  13. PhoneLogGenerator/WritePhoneLogMark
  14. PhoneLogGenerator/WritePhoneLogStartEntry
  15. PhoneLog/--announce--
  16.  
  17.    TITLE
  18.         PhoneLog Developer Kit
  19.  
  20.    VERSION
  21.         1.1
  22.  
  23.    RELEASE DATE
  24.         15.03.1996
  25.  
  26.    AUTHOR
  27.         Kai Hofmann (i07m@zfn.uni-bremen.de)
  28.                     (http://www.informatik.uni-bremen.de/~i07m)
  29.  
  30.    DESCRIPTION
  31.         Generator and parser for programs that want to write and read log
  32.         file entries about modem connections in a standard SGML format.
  33.         Full ANSI-C/C++ source code included.
  34.  
  35.    NEW FEATURES
  36.         - Important bug fixes
  37.         - Improved code
  38.  
  39.    SPECIAL REQUIREMENTS
  40.         ANSI-C or/and C++ Compiler.
  41.  
  42.    AVAILABILITY
  43.         ftp://wuarchive.wustl.edu/pub/aminet/dev/c/PhoneLogDevKit.lha
  44.         And all other Aminet sites.
  45.  
  46.    PRICE
  47.         For NON-COMMERCIAL USE this is Giftware!
  48.         (Non-commercial includes Giftware and Shareware!)
  49.  
  50.         Permission for COMMERCIAL USE is only given by an extra available
  51.         commercial license that must be validated!
  52.         Contact me directly for this license, because it will be individually
  53.         handed out per your needs!
  54.  
  55.         But in both cases you have to follow the two guidelines below:
  56.  
  57.         1) You "must" send me a full version of your product at no cost
  58.            including free updates!
  59.  
  60.    DISTRIBUTION
  61.         You can copy and distribute this source code as long as you do not
  62.         take more than $5 for one disk or $40 for one CD!
  63. PhoneLog/--background--
  64.  
  65.    NAME
  66.         PhoneLog -- Write and read entries to/from a log file (V33)
  67.  
  68.    FUNCTION
  69.         This module has been designed to become a useful and portable library
  70.         and to help developers to write and read entries to/from a log file
  71.         in a standard SGML format.
  72.  
  73.    NOTES
  74.         It seems that there was no standard for log files that are used
  75.         to log modem connections etc.
  76.         So I decided to create a standard based on SGML, because SGML
  77.         uses the ASCII characterset as base, so it can be used on every
  78.         platform. On the other hand SGML gives the log file a real structure
  79.         that is defined by the SGML DTD.
  80.         By supporting this standard with your software you give the user the
  81.         possibility to create or evaluate log files with software from
  82.         different platforms; and you get a standard that is easily extended
  83.         if a need occurs.
  84.  
  85.         SGML : Standard Generalized Markup Language
  86.         DTD  : Document Type Definition
  87.  
  88.         (English) Books which were consulted in creating this library:
  89.             The SGML Handbook
  90.             Charles F. Goldfarb
  91.             First Edition
  92.             Oxford University Press, Walton Street, Oxford (USA) 1990
  93.             ISBN 0-19-853737-9
  94.  
  95.    COPYRIGHT
  96.         This software is copyright 1996 by Kai Hofmann.
  97.         All rights reserved!
  98.  
  99.         - Permission for COMMERCIAL USE is only given by an extra available
  100.           commercial license that must be validated!
  101.           Contact me directly for this license, because it will be
  102.           individually handed out per your needs!
  103.  
  104.         - Permission is hereby granted, without written agreement and without
  105.           license, to USE this software and its documentation for any
  106.           NON-COMMERCIAL purpose, provided that the above copyright notice
  107.           and the following paragraph appear in all copies of this software
  108.           (Non-commercial includes Giftware and Shareware!).
  109.  
  110.         - THERE IS *NO* PERMISSION GIVEN TO REDISTRIBUTE THIS SOFTWARE IN A
  111.           MODIFIED FORM!
  112.  
  113.           You "must" send me a full version of your product at no cost
  114.           including free updates!
  115.           Extra money is welcome (For Bank Account see below - but *ONLY*
  116.           send in DM to this Bank Account!).
  117.  
  118.    DISCLAIMER
  119.         THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
  120.         APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  121.         HOLDER AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  122.         WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  123.         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  124.         A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
  125.         PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
  126.         DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
  127.         CORRECTION.
  128.  
  129.         IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  130.         WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE
  131.         THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
  132.         INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
  133.         ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING
  134.         BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
  135.         LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
  136.         TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
  137.         PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  138.  
  139.         THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
  140.         UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  141.  
  142.    DISTRIBUTION
  143.         Permission is hereby granted, without written agreement and without
  144.         license or royalty fees, to copy and distribute this software and its
  145.         documentation for any purpose, provided that the above copyright
  146.         notice and the following paragraphs appear in all copies of this
  147.         software, to:
  148.         - All who will distribute this software for free!
  149.         - All free accessible INTERNET servers and PHONE boxes!
  150.         - All Aminet sites
  151.         - All SimTel sites
  152.         - Fred Fish for his great Amiga-Software-Library
  153.         - The German SAAR AG PD-Library
  154.         - All others who do NOT take more than $5.- for one disk that
  155.           includes this software!
  156.         - ALL others who do NOT take more than $40.- for one CD that includes
  157.           this software!
  158.  
  159.    ADDITIONAL INFORMATIONS
  160.         I have tried to make portable/useful and I hope bugfree software
  161.         for eternity :)
  162.         So I hope you will pay a fee for this.
  163.  
  164.         Kindly send US - dollars to a friend of mine in the USA who will
  165.         forward it to me in a timely manner.  Please send checks or money
  166.         orders only.
  167.         Contact me via email for more details!
  168.  
  169.    AUTHOR
  170.         Kai Hofmann
  171.         Arberger Heerstraße 92
  172.         28307 Bremen
  173.         Germany
  174.  
  175.         Phone: (+49)-(0)421/480780
  176.                (Remember that my parents don't speak english!)
  177.         EMail: i07m@zfn.uni-bremen.de
  178.                i07m@informatik.uni-bremen.de
  179.         IRC  : PowerStat@#AmigaGer
  180.         WWW  : http://www.informatik.uni-bremen.de/~i07m
  181.  
  182.         Bank account : 1203 7503
  183.         Account owner: Kai Hofmann
  184.         Bank code    : 290 501 01
  185.         Bank name    : Sparkasse in Bremen/Germany
  186.  
  187.     THANKS
  188.         Thank you's are going to the following people:
  189.         Rita Reichl             - For correcting my English.
  190.         James Cooper and the
  191.         other Amiga people at
  192.         SAS Intitute            - For spending their unpaid free time with
  193.                                   continuation of the Amiga SAS C/C++
  194.                                   support :)
  195. PhoneLog/--compiling--
  196.  
  197.    NAME
  198.         compiling -- Specials for compiling the PhoneLog library
  199.  
  200.    COMPILING
  201.         - You could compile this code as normal C or as C++
  202.         - You need only the follwoing files to include:
  203.           PhoneLog.h, PhoneLogGenerator.h, PhoneLogParserInterface.h
  204.           If you want to modifiy the scanner and/or parser, you need the
  205.           following software: Aminet:dev/misc/Toolbox.lha to translate the
  206.           .rex and .lalr file into C code!
  207. PhoneLog/--history--
  208.  
  209.    NAME
  210.         history -- This is the development history of the PhoneLog library
  211.  
  212.    VERSION
  213.         $VER: PhoneLog 1.1 (15.03.96)
  214.  
  215.    HISTORY
  216.         18.02.1996 -    Concept
  217.         19.02.1996 -    Implementation
  218.         05.03.1996 -    Writing Autodocs
  219.         06.03.1996 -    Improving generator and parser
  220.         07.03.1996 -    Wrinting Autodocs and improvements for the parser
  221.         15.03.1996 -    Fixing bugs - now the date/time-format is in
  222.                         correct ISO8601 format
  223.                         closing SGML element now correctly using '/' instead
  224.                         of '\'
  225.                         Better scanner - now supports empty elements
  226.                         Changed SGML DTD - HOSTNAME ist now optional
  227.                         Parser now initialize and insert entry and mark
  228.                         correctly
  229.                         Parser now checks strings for length limitation
  230. PhoneLog/--release--
  231.  
  232.    NAME
  233.         release -- This is the release history of the PhoneLog library
  234.  
  235.    RELEASE
  236.         08.03.1996 : V1.0 -     First release on Aminet
  237.         15.03.1996 : v1.1 -     Second Aminet release
  238. PhoneLog/--todo--
  239.  
  240.    NAME
  241.         todo -- This is the 'To-Do' list of the PhoneLog library
  242.  
  243.    TODO
  244.         Nothing at the moment
  245. PhoneLogGenerator/ClosePhoneLog
  246.  
  247.    NAME
  248.         ClosePhoneLog -- Close a log file (V33)
  249.  
  250.    SYNOPSIS
  251.         ClosePhoneLog(file);
  252.  
  253.         void ClosePhoneLog(FILE *const file);
  254.  
  255.    FUNCTION
  256.         Close a log file opened by OpenPhoneLog().
  257.  
  258.    INPUTS
  259.         file - The stdio.h file descriptor for a level 2 file that you got
  260.             from OpenPhoneLog().
  261.  
  262.    RESULT
  263.         None
  264.  
  265.    EXAMPLE
  266.         ...
  267.         FILE *file;
  268.  
  269.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  270.         ...
  271.         ClosePhoneLog(file);
  272.         ...
  273.  
  274.    NOTES
  275.         None
  276.  
  277.    BUGS
  278.         No known bugs.
  279.  
  280.    SEE ALSO
  281.         OpenPhoneLog(),WritePhoneLogStartEntry(),WritePhoneLogEndEntry(),
  282.         WritePhoneLogEntry(),WritePhoneLogMark()
  283. PhoneLogGenerator/OpenPhoneLog
  284.  
  285.    NAME
  286.         OpenPhoneLog -- Opens a log file for write operations (V33)
  287.  
  288.    SYNOPSIS
  289.         file = OpenPhoneLog(name);
  290.  
  291.         FILE *OpenPhoneLog(const char *const name);
  292.  
  293.    FUNCTION
  294.         Opens a log file for appending new entries. If the log file doesn't
  295.         exist, a new one will be created.
  296.  
  297.    INPUTS
  298.         name - The name of the log file.
  299.  
  300.    RESULT
  301.         file - stdio.h file descriptor for a level 2 file or NULL if an error
  302.             occurs.
  303.  
  304.    EXAMPLE
  305.         ...
  306.         FILE *file;
  307.  
  308.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  309.         ...
  310.         ClosePhoneLog(file);
  311.         ...
  312.  
  313.    NOTES
  314.         None
  315.  
  316.    BUGS
  317.         No known bugs.
  318.  
  319.    SEE ALSO
  320.         ClosePhoneLog(),WritePhoneLogStartEntry(),WritePhoneLogEndEntry(),
  321.         WritePhoneLogEntry(),WritePhoneLogMark()
  322. PhoneLogGenerator/WritePhoneLogEndEntry
  323.  
  324.    NAME
  325.         WritePhoneLogEndEntry -- Write the end to a log file (V33)
  326.  
  327.    SYNOPSIS
  328.         WritePhoneLogEndEntry(file, item);
  329.  
  330.         void WritePhoneLogEndEntry(FILE *const file,
  331.             const struct PhoneLogEntry *const item);
  332.  
  333.    FUNCTION
  334.         Write the end data for a connection to a log file opened by
  335.         OpenPhoneLog() after you have used WritePhoneLogStartEntry()!
  336.  
  337.    INPUTS
  338.         file - The stdio.h file descriptor for a level 2 file that you got
  339.             from OpenPhoneLog().
  340.         item - PhoneLogEntry structure. You must fill in following fields:
  341.             EndDay, EndMonth, EndYear, EndHour, EndMin, EndSec
  342.             If you want you can optionally fill in the fields:
  343.             Hours, Mins, Secs
  344.  
  345.    RESULT
  346.         None
  347.  
  348.    EXAMPLE
  349.         ...
  350.         FILE *file;
  351.         struct PhoneLogEntry item;
  352.  
  353.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  354.         ...
  355.         item.EndDay = 5;
  356.         item.EndMonth = 3;
  357.         item.EndYear = 1996; \* NOT 96! *\
  358.         item.EndHour = 12;
  359.         item.EndMin = 17;
  360.         item.EndSec = 0;
  361.         WritePhoneLogEndEntry(file,item);
  362.         ...
  363.         ClosePhoneLog(file);
  364.         ...
  365.  
  366.    NOTES
  367.         If you want to write the optional fields Hours, Mins, Secs to the log
  368.         file, please remove the second comment from the source code!
  369.         If you want that EndDay, EndMonth and EndYear will only be written
  370.         to the log file if they are different to the start date, then please
  371.         remove the first comment from the source code, but keep in mind
  372.         that you now must fill the structure with StartDay, StartMonth and
  373.         StartYear too!
  374.  
  375.    BUGS
  376.         No known bugs.
  377.  
  378.    SEE ALSO
  379.         OpenPhoneLog(),ClosePhoneLog(),WritePhoneLogStartEntry(),
  380.         WritePhoneLogEntry(),WritePhoneLogMark()
  381. PhoneLogGenerator/WritePhoneLogEntry
  382.  
  383.    NAME
  384.         WritePhoneLogEntry -- Write a full entry to a log file (V33)
  385.  
  386.    SYNOPSIS
  387.         WritePhoneLogEntry(file, item);
  388.  
  389.         void WritePhoneLogEntry(FILE *const file,
  390.             const struct PhoneLogEntry *const item);
  391.  
  392.    FUNCTION
  393.         Write a full entry for a connection to a log file opened by
  394.         OpenPhoneLog().
  395.  
  396.    INPUTS
  397.         file - The stdio.h file descriptor for a level 2 file that you got
  398.             from OpenPhoneLog().
  399.         item - PhoneLogEntry structure. You must fill in following fields:
  400.             Number, Name, StartDay, StartMonth, StartYear, StartHour,
  401.             StartMin, StartSec, EndDay, EndMonth, EndYear, EndHour, EndMin,
  402.             EndSec
  403.             If you want you can optionally fill in the fields:
  404.             Hours, Mins, Secs
  405.  
  406.    RESULT
  407.         None
  408.  
  409.    EXAMPLE
  410.         ...
  411.         FILE *file;
  412.         struct PhoneLogEntry item;
  413.  
  414.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  415.         ...
  416.         strcpy(item.Number,"1234567890");
  417.         strcpy(item.Name,"University");
  418.         item.StartDay = 5;
  419.         item.StartMonth = 3;
  420.         item.StartYear = 1996; \* NOT 96! *\
  421.         item.StartHour = 12;
  422.         item.StartMin = 3;
  423.         item.StartSec = 0;
  424.         item.EndDay = 5;
  425.         item.EndMonth = 3;
  426.         item.EndYear = 1996; \* NOT 96! *\
  427.         item.EndHour = 12;
  428.         item.EndMin = 17;
  429.         item.EndSec = 0;
  430.         WritePhoneLogEntry(file,item);
  431.         ...
  432.         ClosePhoneLog(file);
  433.         ...
  434.  
  435.    NOTES
  436.         If you want to write the optional fields Hours, Mins, Secs to the log
  437.         file, please remove the second comment from the source code of the
  438.         function WritePhoneLogEndEntry().
  439.         If you want that EndDay, EndMonth and EndYear will only be written
  440.         to the log file if they are different to the start date, then please
  441.         remove the first comment from the source code of the function
  442.         WritePhoneLogEndEntry().
  443.  
  444.    BUGS
  445.         No known bugs.
  446.  
  447.    SEE ALSO
  448.         OpenPhoneLog(),ClosePhoneLog(),WritePhoneLogStartEntry(),
  449.         WritePhoneLogEndEntry(),WritePhoneLogMark()
  450. PhoneLogGenerator/WritePhoneLogMark
  451.  
  452.    NAME
  453.         WritePhoneLogMark -- Write a mark to a log file (V33)
  454.  
  455.    SYNOPSIS
  456.         WritePhoneLogMark(file);
  457.  
  458.         void WritePhoneLogMark(FILE *const file);
  459.  
  460.    FUNCTION
  461.         Write a mark to a log file opened by OpenPhoneLog().
  462.  
  463.    INPUTS
  464.         file - The stdio.h file descriptor for a level 2 file that you got
  465.             from OpenPhoneLog().
  466.  
  467.    RESULT
  468.         None
  469.  
  470.    EXAMPLE
  471.         ...
  472.         FILE *file;
  473.  
  474.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  475.         ...
  476.         WritePhoneLogMark(file);
  477.         ...
  478.         ClosePhoneLog(file);
  479.         ...
  480.  
  481.    NOTES
  482.         This function is for programs that evaluate log files only!
  483.         After such a program has parsed the log file it can write a mark,
  484.         so it knows the next time it parses the log file which data is
  485.         already known.
  486.  
  487.    BUGS
  488.         No known bugs.
  489.  
  490.    SEE ALSO
  491.         OpenPhoneLog(),ClosePhoneLog(),WritePhoneLogStartEntry(),
  492.         WritePhoneLogEndEntry(),WritePhoneLogEntry()
  493. PhoneLogGenerator/WritePhoneLogStartEntry
  494.  
  495.    NAME
  496.         WritePhoneLogStartEntry -- Write the start to a log file (V33)
  497.  
  498.    SYNOPSIS
  499.         WritePhoneLogStartEntry(file, item);
  500.  
  501.         void WritePhoneLogStartEntry(FILE *const file,
  502.             const struct PhoneLogEntry *const item);
  503.  
  504.    FUNCTION
  505.         Write the start data for a connection to a log file opened by
  506.         OpenPhoneLog().
  507.  
  508.    INPUTS
  509.         file - The stdio.h file descriptor for a level 2 file that you got
  510.             from OpenPhoneLog().
  511.         item - PhoneLogEntry structure. You must fill in following fields:
  512.             Number, StartDay, StartMonth, StartYear, StartHour,
  513.             StartMin, StartSec.
  514.             The fields Name and Reason are optional and will only be written
  515.             if the string length is greater than 0.
  516.  
  517.    RESULT
  518.         None
  519.  
  520.    EXAMPLE
  521.         ...
  522.         FILE *file;
  523.         struct PhoneLogEntry item;
  524.  
  525.         file = OpenPhoneLog("AmiTCP:log/AmiLog.log");
  526.         ...
  527.         strcpy(item.Number,"1234567890");
  528.         strcpy(item.Name,"University");
  529.         item.StartDay = 5;
  530.         item.StartMonth = 3;
  531.         item.StartYear = 1996; \* NOT 96! *\
  532.         item.StartHour = 12;
  533.         item.StartMin = 3;
  534.         item.StartSec = 0;
  535.         WritePhoneLogStartEntry(file,item);
  536.         ...
  537.         ClosePhoneLog(file);
  538.         ...
  539.  
  540.    NOTES
  541.         Set Reason[0] = '\0' if you not want that this will be written to
  542.         the log file.
  543.  
  544.    BUGS
  545.         No known bugs.
  546.  
  547.    SEE ALSO
  548.         OpenPhoneLog(),ClosePhoneLog(),WritePhoneLogEndEntry(),
  549.         WritePhoneLogEntry(),WritePhoneLogMark()
  550.